/*
 * Copyright 2006-2008 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package net.martinimix.beans.bind;

import java.util.List;

import com.bluemartini.dna.BusinessObject;
import com.bluemartini.dna.BusinessObjectArray;
import com.bluemartini.dna.DNAList;

/**
 * Provides a business object and bean binding service.
 * 
 * @author Scott Rossillo
 * 
 */
public interface BindingService {
	
	/**
	 * Returns a bean of the same type as the given target whose properties
	 * are bound to the contents of the given DNA list.
	 * 
	 * @param source a <code>DNAList</code> providing property values for the
	 * given <code>target</code>
	 * 
	 * @param target an <code>Object</code> whose type will be used to bind the
	 * values in the given <code>source</code>
	 * 
	 * @return the <code>target</code> with its fields bound to the properties
	 * from the given <code>source</code>
	 */
	public Object bindBean(DNAList source, Object target);
	
	/**
	 * Returns a list of beans of the same type as the given target whose fields
	 * are bound to the contents of the given array's business objects.
	 * 
	 * @param source a <code>BusinessObjectArray</code> containing the
	 * <code>BusinessObject</code>s to be bound to beans of the type the given
	 * <code>target</code>
	 * 
	 * @param target an <code>Object</code> whose type will be used to bind the
	 * values in the given <code>source</code>
	 * 
	 * @return a <code>List</code> of same size as <code>source</code> containing
	 * beans whose fields are bound to according to the field mapping strategy
	 * supported by the given <code>target</code> 
	 */
	public List bindBeans(BusinessObjectArray source, Object target);
	
	
	/**
	 * Returns a business object of the given type whose properties are 
	 * set to the field values of the given source object.
	 * 
	 * @param source the <code>Object</code> whose fields will be mapped to
	 * properties on the returned <code>BusinessObject</code>
	 * 
	 * @param type the business object type to be assigned to the returned
	 * <code>BusinessObject</code>; as defined in a Blue Martini
	 * business object definition file
	 * 
	 * @return a <code>BusinessObject</code> whose properties are mapped to the 
	 * fields of the given <code>source</code> object
	 * 
	 * @throws BusinessObjectBindException if an error occurs while instantiating
	 * a <code>BusinessObject</code> of the given <code>type</code>
	 */
	public BusinessObject bindBusinessObject(Object source, String type) throws BusinessObjectBindException; 
	
	/**
	 * Returns an array of business objects whose properties are bound to the fields
	 * of the beans contained in the given list.
	 * 
	 * @param beans the <code>List</code> of beans to bind to business objects of the 
	 * given <code>type</code>
	 *  
	 * @param type the business object type to be assigned to the
	 * <code>BusinessObject</code>s in the returned <code>BusinessObjectArray</code>
	 * as defined in a Blue Martini business object definition file
	 * 
	 * @return a <code>BusinessObjectArray</code> containing the given <code>beans</code>
	 * bound as <code>BusinessObject</code>s
	 * 
	 * @throws BusinessObjectBindException if an error occurs while instantiating
	 * a <code>BusinessObject</code> of the given <code>type</code>
	 */
	public BusinessObjectArray bindBusinessObjects(List beans, String type) throws BusinessObjectBindException;

}
